.TH ME "1" "January 2014" "me" "User Commands"
.SH NAME
me \- MakeMe -- Utility to make and manage programs and products
.SH SYNOPSIS
.B me 
    \fB--benchmark\fR
    \fB--configuration\fR
    \fB--configure /path/to/source\fR
    \fB--continue\fR
    \fB--debug\fR
    \fB--deploy directory\fR
    \fB--depth level\fR
    \fB--diagnose\fR
    \fB--dump\fR
    \fB--endian [big|little]\fR
    \fB--file file.me\fR
    \fB--force\fR
    \fB--gen [make|nmake|sh|vs|xcode|main|start]\fR
    \fB--get field\fR
    \fB--help\fR
    \fB--import\fR
    \fB--keep\fR
    \fB--log logSpec\fR
    \fB--nolocal\fR
    \fB--nocross\fR
    \fB--out path\fR
    \fB--overwrite\fR
    \fB--platform os-arch\fR
    \fB--pre\fR
    \fB--prefix dir=path\fR
    \fB--prefixes [debian|embedthis|opt]\fR
    \fB--profile [debug|release|...]\fR
    \fB--quiet\fR
    \fB--rebuild\fR
    \fB--reconfigure\fR
    \fB--release\fR
    \fB--rom\fR
    \fB--set [feature=value]\fR
    \fB--sets [set,set,...]\fR
    \fB--show\fR
    \fB--static\fR
    \fB--unicode\fR
    \fB--unset feature\fR
    \fB--version\fR
    \fB--verbose\fR
    \fB--watch msec]\fR
    \fB--why]\fR
    \fB--with PACK[=PATH]\fR
    \fB--without PACK\fR
    \fB[targets|actions] ...\fR
.SH DESCRIPTION
MakeMe and its "\fBme\fR" command is modern replacement for the venerable make and not so popular autoconf utilities.
MakeMe manages the building of programs and products by effectively determining which pieces have been updated and 
thus which components need to be rebuilt. It easily handles direct compilation and generation of projects. 
.PP
.SH WHY ME?
Many projects rely on autoconf to configure products and make to build. But autoconf is a baroque maze of scripts and
make is low-level, scales poorly and provides little support for easily building executable and libraries in a cross
platform manner. Furthermor, neither of these tools work well for Windows or embedded platforms like VxWorks.
Consequently, creating portable Makefiles and autoconf scripts that will work on a variety of platforms and support 
cross-compilation is an exercise in patience. Often the result is slow, fragile build systems, especially on Windows.
.PP 
MakeMe replaces both autoconf and make with a single utility: 'me'.
MakeMe provides a higher level of abstraction to easily specify the targets to build (libraries, executables, files and
script output).  It can build directly on Linux, Mac or Windows and cross compile for other platforms. It will generate
native projects for Visual Studio, XCode, Make, Nmake and shell scripts. MakeMe builds fast without the complexity of autoconf
and make.
.PP
MakeMe was initiated after evaluating Make, CMake and GYP for use by Appweb and Ejscript in an embedded, cross-compilation
environment. While all three can be made to work, at Embedthis, we were expending a large percentage of time on the build
system and less on the actual product. Our design goals were:

    . Create a build too to be used by Embedthis for its own products
    . Be portable across the major Unix platforms and Windows
    . Easily manage cross-compilation and cross-compilers for embedded targets
    . Generate native projects for IDE integration
    . Build quickly, reliably and flexibly on Windows without requiring Cygwin
    . Support for the entire build cycle: C dependencies, compilation, test and packaging
    . Support modular discovery, configuration and integration of external third-party packages
    . Be hackable and extendable
.SH FEATURES
MakeMe has the following major features:

    . Configuration and component discovery (replaces autoconf)
    . Compiler capability sleuthing
    . Generation of a configuration source header (me.h)
    . Generation of Xcode, Visual Studio, Make, Nmake and shell script projects
    . Automatic C/C++ source code dependencies
    . Projects can aggregate multiple MakeMe files without using recursion
    . Cross platform. Easily handles Windows, Linux and Mac builds
    . Easy cross-compilation
    . Building outside source tree for read-only file systems
    . MakeMe files are Javascript source and are easily modified and extended
    . Multiple build profiles (debug, release, ...)
    . Very fast configuration and building, even on windows
.SH NICE BITS
While MakeMe has a strong feature set, there are some characteristics that make building with MakeMe especially nice:

    . Unified project view. No "make" style recursion required.
    . MakeMe configuration may be comprised by multiple MakeMe files
    . MakeMe file targets and scripts are relative to their own directory
    . Targets can be named symbolically not just by the target path.
    . MakeMe provides a "why" option (me -why) to display why a target was or was not rebuilt
    . MakeMe files and targets intelligently inherit of outer project properties
    . MakeMe scripts run using the working directory of the MakeMe file
    . Detailed documentation

.PP

.SH OVERVIEW
A MakeMe file is a Javascript file with a '.me' extension that invokes Me.load() to process a set of build instructions. 
The build instructions are expressed as a Javascript object literal that Me.load() integrates into the master set of 
build instructions.
.PP
.RS 5
Me.load({
    targets: {
        /* Build the rocket executable */
        rocket: {
            type: 'exe',
            sources: ['*.c'],
        },
    },
.RE
.RS 5
})
.RE
.PP
To build the rocket, enter:
.PP
.RS 5
\fBme rocket\fR
.RE

.SH INVOCATION
.PP
When 'me' is invoked, it searches for a 'start.me' file in the current directory. If one if not found, it searches
up the parent directory chain for one. MakeMe then loads this 'start.me' file and commences processing its build
instuctions. A 'start.me' may in turn load other MakeMe files.

.SH STANDALONE USES
A standalone start.me file may be used to express simple build targets that do not requiring any prior
configuration step. The 'start.me' file contains targets that specify the recipies to build those targets.

.SH CONFIGURED PRODUCTS
Some products require a configuration phase prior to building with MakeMe. Configuration involves discovering 
the tools and components available on the current system and the available compiler tool chain support.
For configured products, 'me' is first invoked with a "configure" target. MakeMe then reads a 'main.me' file which
describes the project, and generates a 'start.me' and 'platform.me' file that describes the system.

.SH TARGETS
MakeMe is typically invoked with zero or more targets to build. If invoked with zero targets, MakeMe will build all the
out-of-date targets. If a one or more targets are specified, only those targets will be brought up to date.
.RE
.PP
To build all targets:
.RS 5
\fBme\fR
.RE
.PP
To build several named targets:
.RS 5
\fBme libengine librocket space-program \fR
.RE
.PP
MakeMe pre-defines several targets:

    . configure - To configure prior to building
    . build - To build all targets
    . compile - Same as 'build'
    . clean - To clean built targets and prepare for rebuilding
    . rebuild - Clean and build

.SH CONFIGURING
To configure a product before building, run MakeMe using the 'me configure' target or alternatively use the '-config' switch.
When configuring, MakeMe will load a 'main.me' file and use the details from the 'settings' properties to tailor 
the configuration. The settings provide a 'name', 'description', and 'version'.
.PP
For example, this is a typical 'settings' configuration.
.PP
.RS 5
settings: {
    name: 'mpr',
    description: 'Multithreaded Portable Runtime',
    version: '4.0.5',
.RE
.RS 5
},
.PP
The 'configure' properties define the required and optional packages that should be discovered.
.PP
.RE
.RS 5
configure: {
    requires: [ 'osdep' ],
    discovers: [ 'ssl' ],
.RE
.RS 5
},
.RE
.PP
The 'requires' property defines the packages that are required to be present on the system to build. The 
'discovers' property defines those packages that will be used if present, but are not required.

.SH CROSS COMPILING
To build a product for platform different to that of the local system is called cross compiling. Sometimes this
cross compiling is just for a different instruction set (say x64 instead of x86). Other times it is for a completely
different operating system and/or CPU architecture. In such cases a cross-compiler may be required to build for the
target platform.
.PP
MakeMe supports cross compiling via the 'me \fB-platform OS-ARCH\fR configure' switch. This adds a platform to the list of
platforms to be made when building. Multiple platforms may be specified and the 'local' platform alias may be used for the 
local development platform.
.PP
Some products require local building to make tools that are required to build for any platform. These products add
a "platforms: ['local']" property to their settings collection in the main.me file. This automatically adds the local
platform to the platforms list and is the same as adding '-platform local' on the command line when configuring. 
.PP
.RS 5
\fBme\fR --platform windows-x64-debug -configure .
.RE
.PP
This will create a windows-x64-debug.me configuration file and a start.es that references it. The platform switch does not
need to be respecified after configuration.

.SH PROJECT GENERATION
MakeMe can generate generate complete project files for building using: make, nmake, Visual Studio, Xcode or plain shell
scripts. MakeMe uses the '--gen' switch to specify the projects to build. MakeMe is capable of cross-generating projects
for non-native platforms. For example: you can generate an Xcode project for Mac OS X on a Windows system.
.PP
.RS 5
\fBme\fR -continue -platform macosx-x64 configure -gen xcode,make,sh
.RE

.PP
This will generate Xcode, make and shell script projects for a Mac OS X 64-bit. The continue switch indicates that 
generation should continue even if the required compilers and build tools are not present on the development system.

.SH DEPENDENCIES
MakeMe targets can depend on other targets that must be built first. MakeMe targets have a name which may be depended upon
by another target. For example:
.PP
.RS 5
targets {
    first: {
        build: "print('Build First')",
    },
    second: {
        depends: ['first'],
        build: "print('Build Second')",
    },
}
.RE
.PP
Before MakeMe begins building, it parses the entire MakeMe file configuration and determines which targets depend on what.
It then builds the targets in the required build order. It successfully detects and handles dependency loops.

.SH DEFAULTS
Often targets need very similar configuration. MakeMe provides a 'defaults' set of properties that are inherited by
all targets. It also provides an 'internal' set of properties that are inherited by only the targets in the same
MakeMe file. For example:

.RS 5
defaults: {
    '+defines': [ 'TUNE=SPEED ],
    '+libraries': [ 'math' ],
.RE
.RS 5
}
.RE

This will use the 'TUNE=SPEED' compiler define when compiling all source files, and the 'math' library when linking
executables (and libraries on some systems). 

.SH OVERRIDING
MakeMe has default command flags for the compiler, linker and other tools. These can be overridden by providing 
environment variables containing alternate flags to use. Use CFLAGS to provide compiler flags, DFLAGS for 
pre-processor definitions, IFLAGS for compiler include paths and LDFLAGS for linker flags. If these flags are provided
to 'me' when building, they apply to that run only. If the flags are provide when configuring, they are saved in the
generated platform file and apply to all subsequent runs. 

.SH DEBUGGING
With Make and other build tools, it is difficult to determine why a target is or is not being built. MakeMe 
provides a '--why' switch to diagnose problematic build sequences. This switch displays the reason why each target was
or was not built.
.PP
In a complex project containing many MakeMe files, it can be helpful to see the entire MakeMe configuration in one file. Use
the '--dump' switch to save a copy of the entire configuration. In the dump, build defaults are fully expanded to each
target contains the expanded configuration that will be used to build the target.
.PP
By default, MakeMe builds relativley quietly and stops on the first build error. To see the commands MakeMe is issuing, use
the '--show' switch. To build totally quietly, use the '--quiet' switch. To continue building despite build errors, use
the '--continue' switch.

.SH OPTIONS
.TP
\fB\--benchmark\fR
Measure the elapsed time to run 'me'.

.TP
\fB\--configuration\fR
Display the current configuration. This displays the configuration for each package and the build settings.

.TP
\fB\--configure /path/to/source/tree\fR
Configure the project to prepare for building. This configures MakeMe for building the project based on the instructions
specified in a 'main.me' located in the specified path source tree. When run, 'me' will create a platform configuration 
MakeMe file, a build output directory and me.h header. The configuration
directory is of the form: build/OS-ARCH-PROFILE where OS may be freebsd, linux, macosx, solaris, vxworks, windows and ARCH is
arm, mips, ppc, x64 or x86. PROFILE is typically set to debug or release. For example: 'build/macosx-x64-debug'. 

MakeMe will use the settings.required and settings.discover properties in the main.me for a list of packages to use. 
When configuring, MakeMe will search for these packages and will create definitions in the configuration MakeMe file for
later use.

.TP
\fB\--continue\fR
Continue to build despite any build errors. Normal operation is to stop building if any build errors are encountered.

.TP
\fB\--debug\fR
Same as --profile debug

.TP
\fB\--deploy directory\fR
Install the product to the deployment directory. This is useful to stage the required files to install on a system.
Use --sets to define the file sets to deploy.

.TP
\fB\--depth level\fR
Set the unit test depth level.

.TP
\fB\--diagnose\fR
Run MakeMe with stack backtrace display on errors.

.TP
\fB\--dump\fR
Dump the aggregate MakeMe configuration into a single dump MakeMe file.

.TP
\fB\--endian [big|little]\fR
Set the CPU endianness. This is normally detected by the compiler but may be overridden by this switch.

.TP
\fB\--file filename\fR
Use the alternate named MakeMe file instead of start.me or main.me.

.TP
\fB\--force\fR
Override warnings and proceed with the operation. See --overwrite to write over existing files.

.TP
\fB\--gen [make|nmake|sh|vs|xcode|main|start] \fR
Generate files. This option can be used to generate initial start.me or main.me files or IDE project and makefiles. 
The --gen start, option can be used to create a stand-alone sample start.me file. The --gen main, option
can be used to create a sample main.me file when starting a new product.  Project files are created under the 'projects'
directory.  The projects are based on the current configuration. If cross-generating projects, you will typically need to
also use -configure.

.TP
\fB\--get field \fR
Get a field from the MakeMe DOM. This can be used to display any MakeMe file value. Unlike --set, this applies to any MakeMe DOM value
and not just to settings. For example: 'me --get settings.version'.

.TP
\fB\--import\fR
Import the standard MakeMe configuration "makeme" directory into the local source tree.

.TP
\fB\--keep\fR
Keep some intermediate build files. This is currently used by some documentation generation targets.

.TP
\fB\--log logName[:logLevel]\fR
Specify a file to log internal execution messages. MakeMe will log execution related trace to the log file. The log level
specifies the desired verbosity of output. Level 0 is the least verbose and level 5 is the most. The '-v' switch is
an alias for '--log stderr:2'.

.TP
\fB\--nocross\fR
Don't cross-build. Build only for the local development system.

.TP
\fB\--nolocal\fR
Don't build for the local development system. Build only for the cross platforms.

.TP
\fB\--out path\fR
Save MakeMe trace output to a file instead of displaying to the console.

.TP
\fB\--overwrite\fR
Overwrite existing files.

.TP
\fB\--platform os-arch\fR
Add a platform to build for cross-compilation. Multiple platforms can be added. You may use 'local' for the local platform. Options specified after the platform apply to the prior platform. For example: 

    me --platform linux-x86 --without all --platform linux-arm --with ejscript configure

.TP
\fB\--pre\fR
Pre-process a source file to stdout.

.TP
\fB\--prefix dir=path\fR
Set the installation directory prefix. Various products utilize different prefixes. Typical prefixes are:
root, base, state, data, app, vapp, bin, etc, inc, log, spool, src, web.
For those familiar with autoconf, the major autoconf prefixe switches are supported and mapped as follows:
--prefix to root, --bindir to bin, --libdir to lib, --includedir to inc, --sysconfdir to etc, --libexec to app,
--logfiledir to log, --htdocsdir to web, and --manualdir to man.

.TP
\fB\--prefixes debian|embedthis|opt\fR
Select an installation prefix package. Debian specifies the debian recommended installation locations. Embedthis
products install by default with a prefix of /usr/local/lib/PRODUCT and symlink exectuables to /usr/local/bin.
The opt prefix set installs with a prefix of "/opt".

.TP
\fB\--profile [debug|release|...]\fR
Use the specified profile when building. This option is provided once when configuring and the result is saved in
the platform.profile property in the platform.me file. Custom profiles can be added to the main.me or start.me
files.

.TP
\fB\--quiet\fR
Quiet operation. Suppresses output trace.

.TP
\fB\--rebuild\fR
Rebuild the specified targets. Can also use 'me rebuild'.

.TP
\fB\--reconfigure\fR
Re-run configuration using the prior configuration settings.

.TP
\fB\--release\fR
Select the release profile. Same as --profile release.

.TP
\fB\--rom\fR
Configure setting to build for systems without a file system. This enables the ROM file system.
Use the makerom utility to process required files into C source code for building with the application. 

.TP
\fB\--set key=value\fR
Set a settings property to a given value. For example: 'me -set version=1.0' will update the settings.version property.
Use this when running 'me configure' to persist your changes in the configuration MakeMe file.

.TP
\fB\--sets [set,set,...]\fR
Define the groups of files to install. Each product may define different groups. Typical groups are: core, web, doc, test, etc.

.TP
\fB\--show\fR
Show the actual commands executed by MakeMe.

.TP
\fB\--static\fR
Configure to build using static linking instead of shared libraries. Same as --set static=true.

.TP
\fB\--unicode\fR
Set the character size to wide. 

.TP
\fB\--unset key=value\fR
Clear a settings property.
Use this when running 'me configure' to persist your changes in the configuration MakeMe file.

.TP
\fB\--version\fR
Print the \fBejs\fR command version and exit.

.TP
\fB\--verbose\fR
Run in verbose mode with more trace about MakeMe activities.

.TP
\fB\--watch msec\fR
Watch for changes and rebuild if required. This will sleep for the requested number of milliseconds between checking
for changes. This can also be invoked as 'me watch' which will check every second for changes.

.TP
\fB\--why\fR
Display why each target was or was not built.

.TP
\fB\--with PACK[=path]\fR
Build with the named pack located at the optional path. If the path is ommitted, a search is performed for the
pack at default locations. Packs must have a pack description file installed under 'makeme/packs' in the MakeMe installation.

.TP
\fB\--without PACK\fR
Build without the named pack.

.PP
.SH "REPORTING BUGS"
Report bugs to dev@embedthis.com.
.SH COPYRIGHT
Copyright \(co Embedthis Software. MakeMe and Ejscript are a trademarks of Embedthis Software.
.br
.SH "SEE ALSO"
pak
